Skip to content

docs: documentation site with an API reference (ADR 0013) - #20

Merged
Akinzou merged 1 commit into
masterfrom
docs/site
Nov 11, 2026
Merged

Akinzou merged 1 commit into
masterfrom
docs/site

Conversation

@Akinzou

@Akinzou Akinzou commented Nov 11, 2026

Copy link
Copy Markdown
Owner

What

A documentation site at https://akinzou.github.io/MetaTrader5-Python/ (MkDocs + Material + mkdocstrings, GitHub Pages), see ADR 0013:

  • User guide = the README itself, included between snippet markers (HTML comments, invisible on PyPI and GitHub). One source; nothing to keep in sync.
  • API reference generated statically by griffe from the source and type hints. It never imports the package, so the Windows-only MetaTrader5 and the computed __all__ never reach it.
  • Architecture and every ADR, the migration guide and the changelog in one navigation.
  • Docstrings on every public name and method, and on each ErrorKind member.

Guards

  • tests/unit/test_api_reference.py fails on a public name without a reference entry or docstring, a public method without a docstring, or an ErrorKind member that does not say what it means. It was red before the docstrings were written.
  • .github/workflows/docs.yml runs mkdocs build --strict on every PR: a broken link or anchor, a missing README include, or a page left out of the nav fails it. The same workflow deploys from master; the deploy job never runs for PRs or branches.
  • GitHub Pages is enabled with the Actions source.

Verification

  • Local: ruff, ruff format, mypy, pytest (387 passed, 9 skipped: integration/contract without MT5 credentials), check_file_length.py, mkdocs build --strict, twine check --strict, and a dry run of pin_readme_links.py against refs/tags/v3.0.1 (31 links pinned).
  • A broken anchor was injected on purpose and failed the strict build.
  • /code-review high: 10 findings, all fixed. Four docstrings promised more than the code does (retried retcodes, Stop.parse still raising TypeError for a bad kind, Stop.points raising on zero/NaN, Trader "every call returns a Result"); a landing card and the README "Why" omitted that missing quotes are retried too. The PR docs build is merged into the deploy workflow, so the check and the deploy cannot drift apart.

Residual risk

  • Material for MkDocs is in maintenance mode. The config uses no custom hooks or extra plugins, so moving to Zensical (reads mkdocs.yml) stays cheap.
  • The site follows master, so it may describe changes not yet on PyPI. The changelog's Unreleased section names them.
  • The Documentation URL on PyPI appears with the next release; no release is cut for this.

… and the source

MkDocs + Material + mkdocstrings, published to GitHub Pages (ADR 0013).

- The user guide is the README itself, included between snippet markers that
  PyPI and GitHub do not render: one source, no second copy to drift.
- The API reference is read statically by griffe, never imported, and lists
  each public name explicitly, so the Windows-only MetaTrader5 package and the
  computed __all__ never reach it.
- Docstrings on every public name and method, and on each ErrorKind member.
  tests/unit/test_api_reference.py fails on a public name without a reference
  entry or docstring.
- .github/workflows/docs.yml builds with --strict on every pull request and
  deploys the same build from master; broken links, anchors, includes and
  pages left out of the navigation fail it.

Chose MkDocs over Sphinx because autodoc imports the package, which needs
MetaTrader5 mocked on Linux and follows the computed __all__ into the whole
MT5 namespace. Chose one workflow for check and deploy over a job in ci.yml,
because two copies of the build would drift apart.
@Akinzou
Akinzou merged commit 384e4c3 into master Nov 11, 2026
10 checks passed
@Akinzou
Akinzou deleted the docs/site branch November 14, 2026 01:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant